<!DOCTYPE html>
<!--
     SPDX-License-Identifier: CC-BY-SA-4.0
     SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
-->
<!-- Page last generated 2025-02-20 03:16:15 +0000 -->
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>VisualCAmkES | seL4 docs</title>

    <!-- Our stylesheet and theme stylesheet.  Contains bootstrap. -->
    <link rel="stylesheet" href="/assets/css/style.css" type="text/css">
    <!-- Font awesome -->
    <link href="https://use.fontawesome.com/releases/v5.0.8/css/all.css" rel="stylesheet">
    <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
    <!-- Pygments syntax highlighting  -->
    <link rel="stylesheet" href="/assets/css/highlighting/trac.css" type="text/css">
    <link rel="icon" type="image/x-icon" href="/assets/favicon.ico"><script defer data-domain="docs.sel4.systems"
	    src="https://analytics.sel4.systems/js/script.js"></script></head>

  <body class="container-fluid">

    



<header>
  <ul class="row menu">
    <li class="col-xs-12 col-md-2" >
            <a href="https://sel4.systems" class="skip-icon">
              <img class="img-responsive" src="/assets/logo-text-white.svg" alt="seL4 logo" />
            </a>
    </li>
    <li class="col-xs-12 col-md-10 menu">
      <nav aria-label="Banner links">
        <h2><a href="/Resources" />Resources</h2>
        <h2><a href="/processes" />Contributing</a></h2>
        <h2><a href="/projects" />Projects</h2>
        <h2><a href="/Tutorials" />Tutorials</h2>
        <iframe title="DuckDuckGo search bar" src="https://duckduckgo.com/search.html?site=docs.sel4.systems&prefill=Search%20sel4.systems" style="overflow:hidden;margin-bottom:10px; padding:0;height:40px;float:right;border-width: 0px"></iframe>
      </nav>
    </li>
  </ul>
  <div class="clear"></div>
  
<div class="breadcrumbs bootstrap hidden-sm-down">
  <nav class="sel-breadcrumb" aria-label="Breadcrumb" >
    <ol class=" list-unstyled" vocab="http://schema.org/" typeof="BreadcrumbList">
      
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/">
              <span property="name"><b>seL4 Docs</b></span>
            </a>
            <meta property="position" content="1" />
        </li>
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/projects/">
              <span property="name"><b>Projects</b></span>
            </a>
            <meta property="position" content="2" />
        </li>
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/projects/camkes/">
              <span property="name"><b>CAmkES</b></span>
            </a>
            <meta property="position" content="3" />
        </li>
      
        

        
          <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <span property="name">VisualCAmkES</span>
            <meta property="position" content="4" /></li>
          
    </ol>
  </nav>
  <nav class="sel-version" aria-label="Current Versions">
    <ol class="list-unstyled">
      <li class="list-unstyled text-right" style="margin-left:auto; padding:0rem 0rem;">
        Current versions:</li>
      <li class="list-unstyled text-right">
      <a href="/releases/sel4/13.0.0"><b>seL4-13.0.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/microkit/1.4.1"><b>microkit-1.4.1</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/camkes/camkes-3.11.0"><b>camkes-3.11.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/capdl/0.3.0"><b>capDL-0.3.0</b></a></li>
      </ol>
  </nav>
  <div class='clear'></div>
</div>


</header>

    <main>
      <div class="row">
  <div class="hidden-xs col-sm-4 col-md-3 col-lg-2">
    


<div class="sidebar">















    <ul class="nav nav-sidebar">
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4/">seL4</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/l4v/">L4.verified</a>
        </li>
  
    
    

    
        <li class="active">
            <a class="" href="/projects/camkes/">CAmkES</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/capdl/">CapDL</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/elfloader/">Elfloader</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/buildsystem/">seL4 Buildsystem</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/user_libs/">user_libs</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4runtime/">The seL4 run-time</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4webserver/">seL4webserver</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4-tutorials/">seL4 tutorials</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4bench/">sel4bench</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4test/">seL4Test</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/virtualization/">Virtualization</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/camkes-vm/">camkes-vm</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/dockerfiles/">Dockerfiles</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/docsite/">seL4 Documentation website</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4_tools/">seL4_tools</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/microkit/">Microkit</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/hardware_hacks/">Hardware Hacks</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/rust/">Rust</a>
        </li>
  
    </ul>


</div>

  </div>
  <div class="content col-sm-8 col-md-6 col-lg-7 main">
    <h1 id="visualcamkes">VisualCAmkES</h1>
<p>VisualCAmkES, also known as Visualisation of CAmkES, is
a tool that allows one to visually understand a CAmkES system, how it
works and how the different components are connected together. This
makes understanding easier and more intuitive than traversing CAmkES
code. An example of a graph generated by this tool is shown below</p>

<p><img src="VisualCAmkES_Layout_Example.png" alt="Example Output from VisualCAmkES" /></p>

<p>Currently this program loads in a top-level camkes file and generates a
graph from it. It also lets the user interact with the graph (zoom, pan
and move nodes). 
 The tool is a foundation for a
CAmkES IDE. To create a CAmkES IDE, one must first be able to display a
current CAmkES system and allow interaction. And that is what this
project does. Since it was clear that this project should become an IDE
in the future, the code has been written with that in mind.</p>

<p>The tool is written in python, for two reason. Python provides
cross-platform compatibility, which doesn’t require heavy, insecure Java
virtual machine. The tool uses the CAmkES Ast and Parser API, and since
this was written in python, this tool was also written in python.</p>

<p>VisualCAmkES is currently on the <a href="../next">CAmkESNext</a> branch only</p>

<h2 id="how-to-install">How to Install</h2>
<p>Follow the instructions in <a href="../next">CAmkESNext</a> to
obtain a copy of the CAmkES next repo. This tool should be found in
[path/to/camkes-tool]/camkes/visualCAmkES.</p>

<p>Running the tool requires a few added dependencies: Graphviz and
Qt.
 QT is a framework, which includes GUI, Network,
Concurrency and other things. 
 This install procedure
assumes you have the rest of CAmkES working.</p>

<h3 id="installing-qt">Installing Qt</h3>
<p>For Debian/Ubuntu users, there are two ways to
install this. The easy way is to apt-get the items. The “long” way is to
build from source. 
 For Mac (and presumably Windows,
although this is untested for windows): the only way (other than
macports/brew) is to build from source.</p>

<p>Qt is quite big, and the major of it is unnecessary. So I recommend to
build from source for personal computers.</p>

<h4 id="apt-get-method">apt-get method</h4>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">sudo </span>apt-get <span class="nb">install </span>python-pyqt5
<span class="nb">sudo </span>apt-get <span class="nb">install </span>python-pyqt5.qtsvg
</code></pre></div></div>

<h4 id="from-source-method">from source method</h4>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cd</span> /some/temp/directory/like/Downloads
git clone https://github.com/qt/qt5.git
<span class="nb">cd </span>qt5
git checkout 5.5
./init-repository <span class="nt">--no-webkit</span> <span class="nt">--module-subset</span><span class="o">=</span>qtbase,qtsvg

<span class="c"># Check where Qt will install - needed for PyQt5</span>
./configure <span class="nt">--help</span>
<span class="c"># Have a look at where qt will be installed, for me it was installed in /usr/local/Qt-5.5.1</span>

./configure <span class="nt">-release</span> <span class="nt">-nomake</span> examples <span class="nt">-nomake</span> tests <span class="nt">-opensource</span> <span class="nt">-confirm-license</span> <span class="c"># add "-qt-xcb" for linux</span>

make <span class="nt">-j4</span> <span class="c"># This takes a long time (1-3 hrs)</span>
make <span class="nb">install</span>
</code></pre></div></div>

<h3 id="installing-graphviz">Installing Graphviz</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">sudo </span>apt-get <span class="nb">install </span>graphviz
<span class="nb">sudo </span>pip <span class="nb">install </span>graphviz
<span class="nb">sudo </span>pip <span class="nb">install </span>pydotplus
</code></pre></div></div>
<p>For macs, to install
graphviz (first step above), visit this website:
<a href="http://www.ryandesign.com/graphviz/">http://www.ryandesign.com/graphviz/</a> , download the latest development
(or stable as long as greater than version 16), and install the dmg. Pip
will work on the mac.</p>

<h3 id="installing-other-dependencies">Installing other dependencies</h3>
<p>` sudo pip install ansi2html `</p>
<h2 id="how-to-use">How to use</h2>
<p>This program is quite easy to use, yet quite powerful.
To start the application, it would be:</p>

<p>` python [path/to/camkes-tool/camkes]/visualCAmkES `</p>
<h3 id="opening-a-file">Opening a File</h3>
<p>To open a file, click File-&gt;Open. Then select a <strong>top-level
camkes file</strong>. Your graph will load.</p>

<h3 id="manipulating-the-graph">Manipulating the graph</h3>
<p>In the right, you have a few buttons:</p>

<p><img src="VisualCAmkES_userButtons.png" alt="VisualCAmkES Corner UI buttons" /></p>

<p>The button’s name should be self-explanatory.
Autolayout will use graphviz to reposition the nodes into a “nice”
format. In my experience, graphviz never gives a nice layout, but it
does give a good starting point for you.</p>

<p>You can move the instances around by click &amp; dragging each box. The
connections will continually redraw as you move the box. There is a
minimum distance to see the symbol for each connection.</p>

<h3 id="exporting-and-saving">Exporting and Saving</h3>
<p>As you change the graph, <strong>the program automatically saves a .layout file</strong>, 
which contains the current
position of each box. This means that you can close the python
application, and when you reopen it, your latest layout will appear.</p>

<p>You can export an image, into either PNG or SVG.</p>

<ol>
  <li>
    <p>Clicking Save Image or File-&gt;Export Image.</p>
  </li>
  <li>
    <p>Choose either PNG or SVG from the combo-box (first input).</p>

    <p>a.  For PNG, resolutions is mandatory.
 b.  For SVG, no input is mandatory.</p>
  </li>
  <li>Click OK.</li>
  <li>Choose a place to save your file, and name your picture.</li>
</ol>

<h3 id="import-paths">Import Paths</h3>

<p>n some cases, users may have external import paths which is usually a
parameter to the camkes parser. In order to visualise these camkes
projects, the user can add import paths by doing the following:</p>

<ol>
  <li>
    <p>Click Edit -&gt; Add import paths</p>
  </li>
  <li>
    <p>In the dialog box, type (or paste) your import paths. These need to be absolute paths. To add many paths, have spaces between your paths.</p>

    <p>a.  E.g “/home/someUser/camkes-next/projects/FileExtender
     /home/someUser/camkes-next/projects/common”</p>
  </li>
</ol>

<p>A keyboard shortcut is also implemented, Cmd + I or Cmd + I .</p>

<h3 id="key-mappings">Key-mappings</h3>

<p>The key-mappings are as follows:</p>

<table>
  <thead>
    <tr>
      <th>Task</th>
      <th>Linux/Windows</th>
      <th>Mac</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Open</td>
      <td>Ctrl + O</td>
      <td>Cmd + O</td>
    </tr>
    <tr>
      <td>Autolayout</td>
      <td>Ctrl + L</td>
      <td>Cmd + L</td>
    </tr>
    <tr>
      <td>Export (Save) Image</td>
      <td>Ctrl + E</td>
      <td>Cmd + E</td>
    </tr>
    <tr>
      <td>Zoom In</td>
      <td>Ctrl + =</td>
      <td>Cmd + =</td>
    </tr>
    <tr>
      <td>Zoom Out</td>
      <td>Ctrl + -</td>
      <td>Cmd + -</td>
    </tr>
    <tr>
      <td>Add Import Paths</td>
      <td>Ctrl + I</td>
      <td>Cmd + I</td>
    </tr>
  </tbody>
</table>

<h2 id="how-it-works">How it works</h2>
<h3 id="high-level-overview">High level overview</h3>

<p><img style="width: 900px;" src="VisualCAmkES_UML.png" alt="UML Diagram of VisualCAmkES" /></p>

<p>The above is quick UML
class diagram. A few other classes isn’t shown like SaveOptionDialog -
but these are helper classes.</p>

<p>The program is written in object-oriented style, Model-View-Controller
(MVC) paradigm. If you don’t know what MVC is, its pretty much: Model
represents the data, the backend; View represents the front-end, what
the user sees; Controller keeps the Model and View in sync. Qt works on
a Model-View paradigm, which is very similar - except the Controller and
View are the same thing.</p>

<ol>
  <li>GraphController is the QMainWindow - and starts of the program. It
takes the chosen file from the user, gets an AST presentation from
the ASTModel, and passes it on to the GraphWidget (the view).</li>
  <li>GraphWidget will traverse the AST, creating InstanceWidget for
Instances and ConnectionWidget for Connections.</li>
  <li>GraphWidget is a QGraphicsView - containing QGraphicsScene.
InstanceWidget and ConnectionWidget are QGraphicWidget and
QGraphicItem respectively. QGraphicScene handles the placements of
QGraphicItems, and has functions for scaling (i.e. zoom), panning,
moving of nodes etc.</li>
  <li>The program primary works by events. Events are like mouse clicks,
button presses etc.</li>
</ol>

<p>Throughout my code, I use lazy instantiation. Most (if not all) global
variables are declared as properties. Lazy instantiation is when
properties are created only when they are first called. Lazy
instantiation is done because subclasses might have different
expectation of properties’s class.</p>

<p>The getters and settings may trigger other events such as updating the
screen. Furthermore - it seems that when a property is passed down the
different classes, say from GraphWidget to ConnectionWidget, the getter
from GraphWidget is invoked. Hence, events can be triggered in
GraphWidget when ConnectionWidget access the properties.</p>

<h3 id="layout">Layout</h3>
<p>In order to save the layout information - the program
saves a .visualCAmkES.layout file. It starts with a . because it is
purposefully hidden (which won’t work on windows …). This file is a
json file containing dictionaries. The key is the instance name, the
value is another dictionary. The latter dictionary contains the position
and whether it was hidden. Feel free to view the .layout file, but
changing it can risk losing the layout.</p>

<h3 id="additional-implementation-details">Additional implementation details</h3>

<ul>
  <li>When connection widgets are deleted, ConnectionWidget.delete()
      must be called on the object. This is because connection widget
      is tracked by the from and to instance widgets, so it needs to
      delete itself from them.</li>
  <li>Context menu is a bit weirdly implemented. This is what I mean
      by weird: normally you would just create the menu and it all
      works - including closing of the menu. However this doesn’t work
      with QGraphicScenes. So the solution is to add the context menu
      to the scene, and manually close it if the mouse was clicked
      anywhere outside the context menu.</li>
</ul>

<p>Traversing the code using PyCharm IDE is highly recommended.</p>

  </div>







  
    
<div class="sidebar-toc hidden-xs hidden-sm col-md-3 col-lg-3">
    <ul id="toc" class="section-nav">
<li class="toc-entry toc-h2"><a href="#how-to-install">How to Install</a>
<ul>
<li class="toc-entry toc-h3"><a href="#installing-qt">Installing Qt</a>
<ul>
<li class="toc-entry toc-h4"><a href="#apt-get-method">apt-get method</a></li>
<li class="toc-entry toc-h4"><a href="#from-source-method">from source method</a></li>
</ul>
</li>
<li class="toc-entry toc-h3"><a href="#installing-graphviz">Installing Graphviz</a></li>
<li class="toc-entry toc-h3"><a href="#installing-other-dependencies">Installing other dependencies</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#how-to-use">How to use</a>
<ul>
<li class="toc-entry toc-h3"><a href="#opening-a-file">Opening a File</a></li>
<li class="toc-entry toc-h3"><a href="#manipulating-the-graph">Manipulating the graph</a></li>
<li class="toc-entry toc-h3"><a href="#exporting-and-saving">Exporting and Saving</a></li>
<li class="toc-entry toc-h3"><a href="#import-paths">Import Paths</a></li>
<li class="toc-entry toc-h3"><a href="#key-mappings">Key-mappings</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#how-it-works">How it works</a>
<ul>
<li class="toc-entry toc-h3"><a href="#high-level-overview">High level overview</a></li>
<li class="toc-entry toc-h3"><a href="#layout">Layout</a></li>
<li class="toc-entry toc-h3"><a href="#additional-implementation-details">Additional implementation details</a></li>
</ul>
</li>
</ul>
</div>

  
  
<div class="sidebar-toc hidden-xs hidden-sm col-md-3 col-lg-3">
  
    <ul class="section-nav">
    	<h2> CAmkES </h2> 
        <li>
          
          <a style="" class="" href="/projects/camkes/">
            Documentation homepage
          </a>
        </li>


        <li>
          
          <a style="" class="" href="/projects/camkes/status.html">
            Status
          </a>
        </li>












    
        <h3>Useful URLs</h3>
    
        <li>
          <a style="" class="" href="/projects/camkes/manual.html">
            CAmkES Manual
          </a>
        </li>

    
        <li>
          <a style="" class="" href="https://trustworthy.systems/projects/TS/camkes.pml">
            Trustworthy Systems CAmkES project
          </a>
        </li>





    
        <h3>Repositories</h3>
    
        <li>
          <a class="" href="https://github.com/sel4/camkes-tool">
            camkes-tool
          </a>
        </li>

    
        <li>
          <a class="" href="https://github.com/sel4/camkes">
            camkes
          </a>
        </li>

    
        <li>
          <a class="" href="https://github.com/sel4/camkes-manifest">
            camkes-manifest
          </a>
        </li>

    
        <li>
          <a class="" href="https://github.com/sel4proj/global-components">
            global-components
          </a>
        </li>









  
      
          <h3>Releases</h3>
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.9.0.html">
              camkes-3.9.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.8.0.html">
              camkes-3.8.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.7.0.html">
              camkes-3.7.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.6.0.html">
              camkes-3.6.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.5.0.html">
              camkes-3.5.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.4.0.html">
              camkes-3.4.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.3.0.html">
              camkes-3.3.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.2.0.html">
              camkes-3.2.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.11.0.html">
              camkes-3.11.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.10.0.html">
              camkes-3.10.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.1.0.html">
              camkes-3.1.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-3.0.0.html">
              camkes-3.0.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-2.3.1.html">
              camkes-2.3.1
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-2.3.0.html">
              camkes-2.3.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-2.2.0.html">
              camkes-2.2.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-2.1.0.html">
              camkes-2.1.0
            </a>
          </li>
  
      
          <li>
            <a style="" href="/releases/camkes/camkes-2.0.0.html">
              camkes-2.0.0
            </a>
          </li>
  







    </ul>

</div>


</div>

    </main>
    


<footer class="site-footer">

  <h2 class="footer-heading">seL4 docs</h2>

  <div class="footer-col-wrapper">

    <div class="col-md-2">
      



<ul class="social-media-list">
  <li><a href="https://github.com/sel4"><i class="fab fa-github"></i> <span class="username">sel4</span></a></li><li><a href="https://github.com/sel4proj"><i class="fab fa-github"></i> <span class="username">sel4proj</span></a></li>
</ul>

    </div>

    <div class="col-md-8">
      <ul class="list-unstyled">
        <li>
          This site is for displaying seL4 related documentation.  Pull requests are welcome.
        </li>
        
          <li>
            Site last updated: Fri Feb 7 10:17:38 2025 +1100 ee78c8857c
          </li>
          <li>
                Page last updated: Tue Mar 9 13:04:50 2021 +1100 0517ff9e8b
          </li>
        
      </ul>
    </div>
    <div class="col-md-2">
<a href="https://github.com/seL4/docs/blob/master/projects/camkes/visual-camkes/index.md">View page on GitHub</a>
      <br />
      <a href="https://github.com/seL4/docs/edit/master/projects/camkes/visual-camkes/index.md">Edit page on GitHub</a>
      <br />
      <a href="/sitemap">Sitemap</a>
    </div>

  </div>

</footer>

  </body>
</html>
